分頁 ¶

當有太多資料要顯示在單一頁面時，常見的策略是將它們顯示在多個頁面中，並且在每個頁面僅顯示一小部分的資料。此策略稱為分頁。

Yii 使用 yii\data\Pagination 物件來表示關於分頁方案的資訊。特別是，

• 總數 指定資料項目的總數。請注意，這通常遠大於單一頁面上需要顯示的資料項目數量。
• 頁面大小 指定每個頁面包含多少資料項目。預設值為 20。
• 目前頁面 給出目前的頁碼（從零開始）。預設值為 0，表示第一頁。

透過完全指定的 yii\data\Pagination 物件，您可以部分檢索和顯示資料。例如，如果您從資料庫中獲取資料，則可以使用分頁提供的相應值來指定 DB 查詢的 OFFSET 和 LIMIT 子句。以下是一個範例，

use yii\data\Pagination;

// build a DB query to get all articles with status = 1
$query = Article::find()->where(['status' => 1]);

// get the total number of articles (but do not fetch the article data yet)
$count = $query->count();

// create a pagination object with the total count
$pagination = new Pagination(['totalCount' => $count]);

// limit the query using the pagination and retrieve the articles
$articles = $query->offset($pagination->offset)
    ->limit($pagination->limit)
    ->all();

在上面的範例中，將傳回哪一頁文章？這取決於是否給定了名為 page 的查詢參數。預設情況下，分頁將嘗試將目前頁面設定為 page 參數的值。如果未提供參數，則預設為 0。

為了方便建構支援分頁的 UI 元素，Yii 提供了 yii\widgets\LinkPager 小工具，該小工具顯示一個頁面按鈕列表，使用者可以點擊這些按鈕來指示應顯示哪個資料頁面。小工具採用分頁物件，以便它知道目前的頁面以及應顯示多少個頁面按鈕。例如，

use yii\widgets\LinkPager;

echo LinkPager::widget([
    'pagination' => $pagination,
]);

如果您想手動建構 UI 元素，可以使用 yii\data\Pagination::createUrl() 來建立將導向不同頁面的 URL。該方法需要一個頁面參數，並將建立一個包含頁面參數的正確格式化的 URL。例如，

// specifies the route that the URL to be created should use
// If you do not specify this, the currently requested route will be used
$pagination->route = 'article/index';

// displays: /index.php?r=article%2Findex&page=100
echo $pagination->createUrl(100);

// displays: /index.php?r=article%2Findex&page=101
echo $pagination->createUrl(101);

提示： 您可以透過在建立分頁物件時配置 pageParam 屬性來自訂 page 查詢參數的名稱。